Table of Contents
Previous Section
The following tables list the most commonly used NSArray and NSMutableArray methods. The methods covered are grouped in the following categories:
The methods in this section are class methods, as denoted by the plus sign (+). You use class methods to send messages to a class---in this case, NSArray and NSMutableArray. For more information on class methods, see Messaging in WebScript in "Using WebScript."
- + array
- Returns an empty array. Usually used to create NSMutableArrays. NSArrays created with this method are permanently empty.
// Most common use
id mutableArray = [NSMutableArray array];
// May not be what you want
id array = [NSArray array];
- + arrayWithObject:
- Returns an array containing the single specified object.
- + arrayWithObjects:
- Returns an array containing the objects in the argument list. The argument list is a comma-separated list of objects ending with nil.
id array = [NSMutableArray arrayWithObjects:
@"Plates", @"Plasticware", @"Napkins", nil];
- + arrayWithArray:
- Returns an array containing the contents of a specified array. Usually used to create an NSMutableArray from an immutable NSArray. For example, the following statement:
id mutableArray = [NSMutableArray arrayWithArray:@("A", "B", "C")];
- creates an NSMutableArray from a constant NSArray object.
- + arrayWithContentsOfFile:
- Returns an array initialized from the contents of a specified file. The specified file can be a full or relative pathname; the file that it names must contain a string representation of an array, such as that produced by the writeToFile:atomically: method. See also description.
- - count
- Returns the number of objects in the array.
- - isEqual:
- Returns YES if the specified object is an array and has contents equivalent to the receiver, NO otherwise. Two arrays have equal contents if they each hold the same number of objects and objects at a given index in each array satisfy the isEqual: test
- - objectAtIndex:
- Returns the object located at a specified index. Arrays have a zero-based index. The first object in an array is at index 0, the second is at index 1, and so on. It is an error to specify an index that is out of bounds (greater than or equal to the array's count).
- - indexOfObject:
- Returns the index of the first object in the array that is equivalent to a specified object. To determine equality, each element of the array is sent an isEqual: message.
- - indexOfObjectIdenticalTo:
- Returns the index of the first occurrence of the a specified object.
- - sortedArrayUsingSelector:
- Returns an NSArray that lists the receiver's elements in ascending order, as determined by a specified method. This method is used to sort arrays containing strings and/or numbers. For example, the following code excerpt:
id guestArray = @("Suzy", "Alice", "John", "Peggy", "David");
id sortedArray = [guestArray sortedArrayUsingSelector:@ "compare:"];
- creates the NSArray sortedArray containing the string "Alice" at index 0, "David" at index 1, and so on.
Warning: The following methods are not supported by NSArray. They are only available for NSMutableArray objects.
- - addObject:
- Adds a specified object at the end of the receiver. It is an error to specify nil as an argument to this method. You can not add nil to an array.
- - insertObject:atIndex:
- Inserts an object at a specified index. Arrays have a zero-based index. The first object in an array is at index 0, the second is at index 1, and so on.
- It is an error to specify nil as an argument to this method. You can not add nil to an array. It is also an error to specify an index that is out of bounds (greater than or equal to the array's count).
- - removeObject:
- Removes all objects in the array equivalent to a specified object. Equivalency is determined using the isEqual: method.
- - removeObjectIdenticalTo:
- Removes all occurrences of a specified object.
- - removeObjectAtIndex:
- Removes the object at a specified index and moves all elements beyond the index up one slot to fill the gap. Arrays have a zero-based index. The first object in an array is at index 0, the second is at index 1, and so on.
- It is an error to specify an index that is out of bounds (greater than or equal to the array's count).
- - removeAllObjects
- Empties the receiver of all of its elements.
- - setArray:
- Empties the receiver of all its elements, then adds the contents of a specified array.
- - writeToFile:atomically:
- Writes the array's string representation to a specified file using the description method. Returns YES on success and NO on failure. If YES is specified for atomically:, this method attempts to write the file safely so that an existing file with the specified path is not overwritten, and it does not create a new file at the specified path unless the write is successful. The resulting file is suitable for use with arrayWithContentsOfFile:. For example, the following code excerpt:
id guestArray = [NSMutableArray arrayWithContentsOfFile:path];
[guestArray addObject:newGuest];
[guestArray writeToFile:path atomically:YES];
- creates guestArray with the contents of the specified file, adds a new guest, and saves the changes to the same file.
- - description
- Returns a string that represents the contents of the receiver. For example, the following code excerpt:
id array = [NSMutableArray arrayWithObjects:
@"Plates", @"Plasticware", @"Napkins", nil];
id description = [array description];
- produces the string "(Plates, Plasticware, Napkins)".
- - componentsJoinedByString:
- Returns an NSString created by interposing a specified string between the elements of the receiver's objects. Each element of the array must be a string. If the receiver has no elements, an empty string is returned. See also componentsSeparatedByString: (NSString and NSMutableString). For example, the following code excerpt:
id commaString = @"A, B, C";
id array = [string componentsSeparatedByString:@","];
id dash String = [array componentsJoinedByString:@ "-"];
- creates the NSString dashString with the contents "A-B-C".
Table of Contents
Next Section